<!--
    Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
-->


<html>
<head>
</head>
<body>
<p>Jena N3 Parser, RDF Reader and Writer</p>
<p>This package contains</p>
<ul>
  <li>an N3 parser</li>
  <li>a Jena reader, for reading the RDF subset 
of N3 into a Model</li>
  <li>a Jena writer for outputting RDF in an N3 syntax.</li>
</ul>

<p>The N3 writer is aimed at producing readable N3 and analysies the model 
before writing.&nbsp; It may unsuitable for some forms of very large model.</p>

<p>This package does not contains a rules engine to interprete or execute N3 
formulae.&nbsp; It is not a replacement for
<a href="http://www.w3.org/2000/10/swap/doc/cwm">cwm</a>; this system aims to 
provide daat input fo RDF in N3 format.</p>

<p><b>The Parser</b></p>

<p>The N3 parser provided parses the whole of the N3 language.&nbsp; It is a 
streaming parser that emits parser events (see the class N3ParserEventHandler) 
when a new triple is encountered.</p>

<p>It is a permissive parser, it does not aim to validate an N3 and might even 
parse some constructs which are not valid (examples include named formulae and 
named DAML lists;&nbsp; the generated parser events do not expressive the named 
objects).&nbsp; It does not check the characters comprising URIs and is more 
permissive on qnames that strict defintion would require.</p>

<p>The parser is built using <a href="http://antlr.org/">antlr</a>. The grammar 
file is &quot;n3.g&quot;.&nbsp; An application will need access to the antlr runtime 
classes which are provided in antlr.jar in the Jena lib/ directory.
</p>

<p>There is a simple application in jena.n3 that accesses the N3 parser directly 
or via the RDF generator for file conversion or for simple file checking.</p>

<p><b>The RDF generator</b></p>

<p>The RDF generator takes a stream of parser events and turns them into 
additions to a Jena model.&nbsp; The Jena reader is then a class that wraps up 
this functionality to conform to the Jena reader interface.&nbsp; The RDF 
generator does not allow formulae and will cause an error if one is encountered.</p>

<p><b>Performance</b></p>

<p>The parser alone runs at about 18K triples/second on Pentium4 750Mhz PC (it 
is I/O bound in the lexer).&nbsp; When generating RDF, the rate is about 9K 
statements/second.</p>

<p><b>Notes</b></p>

<p>N3 files are UTF-8: not raw bytes or ISO-8859-1.&nbsp; Applications should 
pass UTF-8 character set readers and writers to the appropriate Jena operations 
model.read and model.write.&nbsp; Often, this does not make a difference but can 
cause silent loss or change of character information.</p>

<p><b>Other Information on N3</b></p>
<ul>
  <li><a href="http://www.w3.org/2000/10/swap/doc/cwm">
  http://www.w3.org/2000/10/swap/doc/cwm</a></li>
  <li><a href="http://www.w3.org/DesignIssues/Notation3.html">
http://www.w3.org/DesignIssues/Notation3.html</a></li>
  <li><a href="http://infomesh.net/2002/notation3/">http://infomesh.net/2002/notation3/</a></li>
  <li><a href="http://notabug.com/2002/n3/">http://notabug.com/2002/n3/</a></li>
  <li><a href="http://www.agfa.com/w3c/euler">http://www.agfa.com/w3c/euler</a></li>
</ul>
<p><b>Acknowledgements</b></p>

<p>The grammar was not written from scratch.&nbsp; The grammar is based on
<a href="http://www.w3.org/2000/10/swap/doc/cwm">cwm</a>, <a href="http://www.w3.org/2000/10/swap/rdfn3.g">Dan Connerly's 
python grammar</a> and <a href="http://ninebynine.org/Software/Intro.html">Graham Klyne's N3Parser</a> 
as well as &quot;Notation3 : A Rough Guide&quot; which lists other parsers.</p>
</body>
